/*
 * Metaverse Core
 * Copyright (C) 2010 Vyacheslav Vorobyov, All rights reserved.
 * See LICENSE for full license information.
 */
package org.metaverse.warehouse;

import org.openrdf.model.URI;
import org.singularity.io.CloseableIterator;

/**
 * This is a service interface for contexts control. It allows vital 
 * routines for creation and share contexts to other users.
 * 
 * @author vjache
 *
 */
public interface ContextControl {
	/**
	 * The level of control of a context.
	 * 
	 * @author vjache
	 *
	 */
	enum Level
	{
		/**
		 * Only read allowed.
		 */
		Read,
		/**
		 * Read, write, and delete own statements that created by user allowed.
		 */
		Read_Write_DeleteOwn,
		/**
		 * Read, write, delete any statements allowed.
		 */
		Read_Write_Delete,
		/**
		 * Full control, including ability to share context or destroy it.
		 */
		Owner
	}
	/**
	 * Create a new context provided with a local name.
	 * @param aLocalName - a local name (like "My_favorite_context")
	 * @return a full identifier of context created (like "http://www.metaverse.org/db1/user1/My_favorite_context")
	 */
	URI  createContext(String aLocalName);
	/**
	 * Completely remove context with its content from a warehouse.
	 * @param aContext a full identifier of context to be deleted.
	 */
	void destroyContext(URI aContext);
	/**
	 * Share(or change share) context to someone giving a specified level of access.
	 * @param aContext - a full identifier of context to share
	 * @param aLevel - an access level given
	 * @param aUsers - a users to share to
	 */
	void shareContext(URI aContext, Level aLevel, URI...aUsers);
	/**
	 * Exclude a user from a context.
	 * @param aContext - a full identifier of a context user exclude from
	 * @param aUsers - a users to exclude
	 */
	void unshareContext(URI aContext, URI...aUsers);
	/**
	 * Return a list of contexts where current user has at least a 
	 * specified access level.
	 * @param aLevel - access level
	 * @return - a list of a full identifiers of a contexts
	 */
	CloseableIterator<URI> enlistContexts(Level aLevel);
}
